<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="chrome=1">
    <title>Jumper by Yonaba</title>

    <link rel="stylesheet" href="stylesheets/styles.css">
    <link rel="stylesheet" href="stylesheets/pygment_trac.css">
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <!--[if lt IE 9]>
    <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
  </head>
  <body>
    <div class="wrapper">
      <header>
        <h1>Jumper</h1>
        <p>Fast, lightweight and easy-to-use pathfinding library for grid-based games</p>

        <p class="view"><a href="https://github.com/Yonaba/Jumper">View the Project on GitHub <small>Yonaba/Jumper</small></a></p>


        <ul>
          <li><a href="https://github.com/Yonaba/Jumper/zipball/master">Download <strong>ZIP File</strong></a></li>
          <li><a href="https://github.com/Yonaba/Jumper/tarball/master">Download <strong>TAR Ball</strong></a></li>
          <li><a href="https://github.com/Yonaba/Jumper">View On <strong>GitHub</strong></a></li>
        </ul>
      </header>
      <section>
        <h1>Jumper</h1>

<p><a href="http://travis-ci.org/Yonaba/Jumper"><img src="http://travis-ci.org/Yonaba/Jumper.png" alt="Build Status"></a></p>

<p><strong>Jumper</strong> is a pathfinding library designed for grid-based games. It aims to be <strong>fast</strong> and <strong>lightweight</strong>.
It features a wide range of search algorithms, built within a clean interface with 
chaining features which makes it <strong>very friendly and easy to use</strong>.<br></p>

<p><strong>Jumper</strong> is written in pure <a href="http://lua.org">Lua</a>. Thus, it is not <strong>framework-related</strong> and can be used in any project embedding <a href="http://lua.org">Lua</a> code.</p>

<p></p><img src="http://ompldr.org/vZjltNQ" alt="" width="500" height="391" border="0">

<h3>Contents</h3>

<ul>
<li><a href="http://github.com/Yonaba/Jumper#installation">Installation</a></li>
<li><a href="http://github.com/Yonaba/Jumper#example-of-use">Example of Use</a></li>
<li><a href="http://github.com/Yonaba/Jumper#api--docs">API &amp; Docs</a></li>
<li><a href="http://github.com/Yonaba/Jumper#credits-and-thanks">Credits and Thanks</a></li>
<li><a href="http://github.com/Yonaba/Jumper#license">License</a></li>
</ul><h2>Installation</h2>

<p>The current repository can be retrieved locally on your computer via:</p>

<h3>Bash</h3>

<div class="highlight"><pre>git clone git://github.com/Yonaba/Jumper.git
</pre></div>

<h3>Download (latest)</h3>

<ul>
<li>
<strong>Development release</strong>: <a href="http://github.com/Yonaba/Jumper/zipball/master">zip</a> | <a href="http://github.com/Yonaba/Jumper/tarball/master">tar.gz</a>
</li>
<li>
<strong>Stable release (1.8.1)</strong>: <a href="http://github.com/Yonaba/Jumper/archive/jumper-1.8.1-1.zip">zip</a> | <a href="http://github.com/Yonaba/Jumper/archive/jumper-1.8.1-1.tar.gz">tar.gz</a>
</li>
<li>
<strong>All releases</strong>: <a href="http://github.com/Yonaba/Jumper/tags">tags</a>
</li>
</ul><h2>Example of Use</h2>

<p>Here is a simple example explaining how to use Jumper:</p>

<div class="highlight"><pre><span class="c1">-- Usage Example</span>
<span class="c1">-- First, set a collision map</span>
<span class="kd">local</span> <span class="n">map</span> <span class="o">=</span> <span class="p">{</span>
    <span class="p">{</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">},</span>
    <span class="p">{</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">},</span>
    <span class="p">{</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">},</span>
    <span class="p">{</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">},</span>
<span class="p">}</span>
<span class="c1">-- Value for walkable tiles</span>
<span class="kd">local</span> <span class="n">walkable</span> <span class="o">=</span> <span class="mi">0</span>

<span class="c1">-- Library setup</span>
<span class="kd">local</span> <span class="n">Grid</span> <span class="o">=</span> <span class="nb">require</span> <span class="p">(</span><span class="s2">"</span><span class="s">jumper.grid"</span><span class="p">)</span> <span class="c1">-- The grid class</span>
<span class="kd">local</span> <span class="n">Pathfinder</span> <span class="o">=</span> <span class="nb">require</span> <span class="p">(</span><span class="s2">"</span><span class="s">jumper.pathfinder"</span><span class="p">)</span> <span class="c1">-- The pathfinder lass</span>

<span class="c1">-- Creates a grid object</span>
<span class="kd">local</span> <span class="n">grid</span> <span class="o">=</span> <span class="n">Grid</span><span class="p">(</span><span class="n">map</span><span class="p">)</span> 
<span class="c1">-- Creates a pathfinder object using Jump Point Search</span>
<span class="kd">local</span> <span class="n">myFinder</span> <span class="o">=</span> <span class="n">Pathfinder</span><span class="p">(</span><span class="n">grid</span><span class="p">,</span> <span class="s1">'</span><span class="s">JPS'</span><span class="p">,</span> <span class="n">walkable</span><span class="p">)</span> 

<span class="c1">-- Define start and goal locations coordinates</span>
<span class="kd">local</span> <span class="n">startx</span><span class="p">,</span> <span class="n">starty</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span><span class="mi">1</span>
<span class="kd">local</span> <span class="n">endx</span><span class="p">,</span> <span class="n">endy</span> <span class="o">=</span> <span class="mi">5</span><span class="p">,</span><span class="mi">1</span>

<span class="c1">-- Calculates the path, and its length</span>
<span class="kd">local</span> <span class="n">path</span><span class="p">,</span> <span class="n">length</span> <span class="o">=</span> <span class="n">myFinder</span><span class="p">:</span><span class="n">getPath</span><span class="p">(</span><span class="n">startx</span><span class="p">,</span> <span class="n">starty</span><span class="p">,</span> <span class="n">endx</span><span class="p">,</span> <span class="n">endy</span><span class="p">)</span>
<span class="k">if</span> <span class="n">path</span> <span class="k">then</span>
  <span class="nb">print</span><span class="p">((</span><span class="s1">'</span><span class="s">Path found! Length: %.2f'</span><span class="p">):</span><span class="n">format</span><span class="p">(</span><span class="n">length</span><span class="p">))</span>
    <span class="k">for</span> <span class="n">node</span><span class="p">,</span> <span class="n">count</span> <span class="k">in</span> <span class="n">path</span><span class="p">:</span><span class="n">iter</span><span class="p">()</span> <span class="k">do</span>
      <span class="nb">print</span><span class="p">((</span><span class="s1">'</span><span class="s">Step: %d - x: %d - y: %d'</span><span class="p">):</span><span class="n">format</span><span class="p">(</span><span class="n">count</span><span class="p">,</span> <span class="n">node</span><span class="p">.</span><span class="n">x</span><span class="p">,</span> <span class="n">node</span><span class="p">.</span><span class="n">y</span><span class="p">))</span>
    <span class="k">end</span>
<span class="k">end</span>

<span class="c1">--&gt; Output:</span>
<span class="c1">--&gt; Path found! Length: 8.83</span>
<span class="c1">--&gt; Step: 1 - x: 1 - y: 1</span>
<span class="c1">--&gt; Step: 2 - x: 1 - y: 3</span>
<span class="c1">--&gt; Step: 3 - x: 2 - y: 4</span>
<span class="c1">--&gt; Step: 4 - x: 4 - y: 4</span>
<span class="c1">--&gt; Step: 5 - x: 5 - y: 3</span>
<span class="c1">--&gt; Step: 6 - x: 5 - y: 1</span>
</pre></div>

<p>Find some other examples of use for <strong>Jumper</strong>, made with various Lua-based frameworks and game engines in this separated repository: <a href="http://github.com/Yonaba/Jumper-Examples">Jumper-Examples</a></p>

<h2>API &amp; Docs</h2>

<p>Find a complete documentation and API description online: <a href="http://yonaba.github.com/Jumper/docs">Jumper Documentation</a></p>

<h2>Credits and Thanks</h2>

<ul>
<li>
<a href="http://users.cecs.anu.edu.au/%7Edharabor/home.html">Daniel Harabor</a>, <a href="http://www.grastien.net/ban/">Alban Grastien</a> : for <a href="http://users.cecs.anu.edu.au/%7Edharabor/data/papers/harabor-grastien-aaai11.pdf">their work on Jump Point Search</a>.<br>
</li>
<li>
<a href="http://github.com/qiao">XueXiao Xu</a>, <a href="http://github.com/aniero">Nathan Witmer</a>: for their <a href="http://github.com/qiao/PathFinding.js">JavaScript port</a> <br>
</li>
<li>
<a href="http://github.com/stevedonovan">Steve Donovan</a>: for the awesome documentation generator tool <a href="http://github.com/stevedonovan/ldoc/">LDoc</a>.</li>
<li>
<a href="http://github.com/srdjan-m">Srdjan Markovic</a>, who reported various bugs and feedbacks.</li>
</ul><h2>License</h2>

<p>This work is under <a href="http://www.opensource.org/licenses/mit-license.php">MIT-LICENSE</a><br>
Copyright (c) 2012-2013 Roland Yonaba.</p>

<blockquote>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy<br>
of this software and associated documentation files (the "Software"), to deal<br>
in the Software without restriction, including without limitation the rights<br>
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell<br>
copies of the Software, and to permit persons to whom the Software is<br>
furnished to do so, subject to the following conditions:<br><br>
The above copyright notice and this permission notice shall be included in<br>
all copies or substantial portions of the Software.<br><br>
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR<br>
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,<br>
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE<br>
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER<br>
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,<br>
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN<br>
THE SOFTWARE.</p>
</blockquote>
      </section>
      <footer>
        <p>This project is maintained by <a href="https://github.com/Yonaba">Yonaba</a></p>
        <p><small>Hosted on GitHub Pages &mdash; Theme by <a href="https://github.com/orderedlist">orderedlist</a></small></p>
      </footer>
    </div>
    <script src="javascripts/scale.fix.js"></script>
              <script type="text/javascript">
            var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
            document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
          </script>
          <script type="text/javascript">
            try {
              var pageTracker = _gat._getTracker("UA-33850683-1");
            pageTracker._trackPageview();
            } catch(err) {}
          </script>

  </body>
</html>